home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 20 / Cream of the Crop 20 (Terry Blount) (1996).iso / program / recio214.zip / DESIGN.TXT < prev    next >
Text File  |  1996-06-14  |  18KB  |  397 lines
  1.     Title: RECIO DESIGN AND DEVELOPMENT NOTES
  2. Copyright: (C) 1994-1996, William Pierpoint
  3.   Version: 2.14
  4.      Date: June 14, 1996
  5.  
  6.  
  7.  
  8. 1.0 DATA STRUCTURES
  9.  
  10. 1.1 REC structure for each record stream
  11.  
  12.     * defined in recio.h.
  13.     * 3 (!dos) or 4 (dos) static RECs for recin, recout, etc (included in
  14.       ROPEN_MAX count).
  15.     * allocate dynamic array of RECs dimensioned to ROPEN_MAX-NREC in ropen().
  16.     * Each REC has two associated buffers:
  17.       1) record string buffer containing current record;
  18.          allocate when first record read;
  19.          reallocate if record becomes larger.
  20.       2) field string buffer containing current field;
  21.          allocate when first field read;
  22.          reallocate if field becomes larger.
  23.     * deallocate dynamic RECs and associated buffers in rclose() and
  24.       rcloseall() if all record streams closed; deallocate associated
  25.       buffers for recin with an exit function registered with atexit().
  26.  
  27.  
  28. 1.2 REC r_flags assignments
  29.  
  30.     Bit        Description
  31.    -----    -------------------------------------------------------------
  32.      0        If clear, colno start at 0; if set, colno start at 1
  33.      1      if clear, read mode; if set, write/append mode
  34.      2      if clear, current field not quoted by r_txtch;
  35.             if set, current field quoted by r_txtch.
  36.     3-6     Reserved for future use.
  37.      7        If clear, EOF not reached; if set, EOF reached
  38.     8-11    If clear, no error; else rerror number
  39.    12-15    if clear, no warning; else rwarning number
  40.  
  41.  
  42. 1.3 Accessing REC Members and Associated Buffers
  43.  
  44.     How do I
  45.     * access the name of the record stream?           rnames()
  46.     * access the current context number?              rcxtno()
  47.     * access the current record number?               rrecno()
  48.     * access the current field number?                rfldno()
  49.     * access the current column number?               rcolno()
  50.     * access the record string buffer?                rrecs()
  51.     * access the field string buffer?                 rflds()
  52.     * determine the number of fields in a record?     rnumfld()
  53.     * determine if column numbers start at 0 or 1?    rbegcolno()
  54.     * determine if the current field was quoted?      ristxtfld()
  55.     * determine if there are more records left?       reof()
  56.     * determine if there is an error on the stream?   rerror()
  57.     * determine if there is a warning on the stream?  rwarning()
  58.     * access the error message for the stream?        rerrstr()
  59.     * force an error on a record stream?              rseterr()
  60.     * clear an error on a record stream?              rclearerr()
  61.     * scan the record buffer more than once?          rresetrec()
  62.     * increase the size of the record string buffer?  rsetrecsiz()
  63.     * increase the size of the field string buffer?   rsetfldsiz()
  64.     * replace the data in the field string buffer?    rsetfldstr()
  65.     * replace the data in the record string buffer?   rsetrecstr()
  66.     * get/set position of a field in a record?        rgetfldpos()/rsetfldpos()
  67.     * set the field delimiter character?              rsetfldch()
  68.     * set the text delimiter character?               rsettxtch()
  69.     * set the time format string?                     rsettmfmt()
  70.     * set the context number?                         rsetcxtno()
  71.     * set column numbering to start at 0 or 1?        rsetbegcolno()
  72.     * dynamically copy a string?                      scpys()
  73.     * dynamically concatenate a string?               scats()
  74.     * trim white space from the ends of a string?     strims()
  75.  
  76.  
  77.  
  78. 2.0 CODE STRUCTURES
  79.  
  80. 2.1 RECIO Structure Chart
  81.  
  82.     ╔═════════╗                  ╔═════════╗
  83.     ║ rstr.c  ║                  ║ recio.c ║
  84.     ╚════╤════╝                  ╚═╤══╤══╤═╝
  85.          │                         │  │  │
  86.          │    ╔════════╗     input │  │  │ output   ╔════════╗
  87.          └────╢ rget.c ╟───────────┘  │  └──────────╢ rput.c ║
  88.        char   ╚═╤════╤═╝ column       │      char   ╚═╤════╤═╝ column
  89.      delimited  │    │  delimited     │    delimited  │    │  delimited
  90.     ╔═════════╗ │    │ ╔══════════╗   │   ╔═════════╗ │    │ ╔══════════╗
  91.     ║ rgetf.c ╟─┤    ├─╢ rcgetf.c ║   │   ║ rputf.c ╟─┤    ├─╢ rcputf.c ║
  92.     ╚═════════╝ │    │ ╚══════════╝   │   ╚═════════╝ │    │ ╚══════════╝
  93.                 │    │                │               │    │
  94.     ╔═════════╗ │    │ ╔══════════╗   │   ╔═════════╗ │    │ ╔══════════╗
  95.     ║ rgets.c ╟─┤    ├─╢ rcgets.c ║   │   ║ rputs.c ╟─┤    ├─╢ rcputs.c ║
  96.     ╚═════════╝ │    │ ╚══════════╝   │   ╚═════════╝ │    │ ╚══════════╝
  97.                 │    │                │               │    │
  98.     ╔═════════╗ │    │ ╔══════════╗   │   ╔═════════╗ │    │ ╔══════════╗
  99.     ║ rgett.c ╟─┤    ├─╢ rcgett.c ║   │   ║ rputt.c ╟─┤    ├─╢ rcputt.c ║
  100.     ╚═════════╝ │    │ ╚══════════╝   │   ╚═════════╝ │    │ ╚══════════╝
  101.                 │    │                │               │    │
  102.     ╔═════════╗ │    │ ╔══════════╗   │   ╔═════════╗ │    │ ╔══════════╗
  103.     ║ rbget.c ╟─┘    └─╢ rcbget.c ║   │   ║ rbput.c ╟─┘    └─╢ rcbput.c ║
  104.     ╚═════════╝        ╚══════════╝   │   ╚═════════╝        ╚══════════╝
  105.                                       │
  106.                        ╔══════════╗   │   ╔═════════╗        ╔══════════╗
  107.                        ║ rwarn.c  ╟───┴───╢ rerr.c  ╟────────╢  rfix.c  ║
  108.                        ╚════╤═════╝       ╚════╤════╝        ╚══════════╝
  109.                             │                  │
  110.                        ╔════╧═════╗       ╔════╧════╗
  111.                        ║ rwmsg.c  ║       ║ remsg.c ║
  112.                        ╚══════════╝       ╚═════════╝
  113.  
  114.  
  115. 2.2 Callback Error Functions
  116.  
  117.     The callback error function technique used by the RECIO library can
  118.     be applied within your programs to other abstract data types.  For
  119.     abstract data types within the standard C library, you will need to
  120.     write wrapper functions.
  121.  
  122.                                  ╔═════════╗
  123.                                  ║ errnofn ║
  124.                                  ╚════╤════╝
  125.                                       │
  126.                        ┌──────────────┼──────────────┬───── etc
  127.                        │              │              │
  128.                   ╔════╧════╗    ╔════╧════╗    ╔════╧════╗
  129.                   ║ rerrfn  ║    ║ ferrfn  ║    ║ merrfn  ║
  130.                   ╚═════════╝    ╚═════════╝    ╚═════════╝
  131.              REC            FILE          MEMORY
  132.  
  133.  
  134. 2.2.1 Errno Callback Error Function Skeleton [errnofn()]
  135.  
  136.     switch on error number [errno]
  137.     case out of memory [ENOMEM]
  138.     case out of range [ERANGE]
  139.     case out of record or file pointers [EMFILE]
  140.     case permission denied [EACCES]
  141.     case invalid argument [EINVAL]
  142.     default [anything else]
  143.     endcase
  144.  
  145.  
  146. 2.2.2 RECIO Callback Error Function Skeleton [rerrfn(rp)]
  147.  
  148.     if valid record pointer [risvalid(rp)]
  149.         if past end of file [reof(rp)]  (if reof test removed, past EOF will
  150.         else [error number set]           become R_EMISDAT or R_WEMPSTR)
  151.             switch on error number [rerror(rp)]
  152.             case read data errors [R_ERANGE || R_EINVDAT || R_EMISDAT]
  153.             case write data errors [R_ENOPUT]
  154.                 switch on context number [rcxtno(rp)]
  155.                 case RECIN
  156.                     switch field number [rfldno(rp)]
  157.                     case 1 (first field read)
  158.                     case 2 (second field read)
  159.                     ...
  160.                     endcase
  161.                 ...
  162.                 default [missing or unknown context number]
  163.                 endcase
  164.             case out of memory [R_ENOMEM]
  165.             case fatal errors [R_EINVAL || R_EINVMOD]
  166.             default [anything else]
  167.             endcase
  168.         endif
  169.     else [invalid record pointer]
  170.         call error function that handles errno errors [errnofn()]
  171.     endif
  172.  
  173.  
  174. 2.3 RECIO Callback Warning Function Skeleton [rwarnfn(rp)]
  175.  
  176.     if valid record pointer [risvalid(rp)]
  177.         switch on warning number [rwarning(rp)]
  178.         case read data warnings [R_WEMPSTR || R_WTMFMT]
  179.         case write data warnings [R_WWIDTH]
  180.